/**
 * @author: 團長
 * @date: 2013-9-11-下午5:30:07
 */
package net.loyintean.pearlshell.base.model;

/** 操作结果接口。
 * <p />
 * 这个接口中抛出的各种异常，实质都只是提醒编码人员注意避免此种异常发生。它们应该在开发阶段被消除，而不应出现在生产环境上。
 * <p>
 * 2014-3-12 Loy: add two method ( {@link #fail(String)} and
 * {@link #exception(String, Exception)} ) without data. v2.0.0
 * 
 * @author 團長
 * @since 2014-3-12
 * @version 2.0.0
 * @deprecated 请使用 {@link IResultData} */
@Deprecated
public interface IResult<T> {

	/** 获取操作信息。
	 * <p>
	 * 如果操作结果是初始化或者成功，将返回'INIT'或'SUCCESS’，否则将返回失败信息或者异常信息
	 * 
	 * @author 團長
	 * @since 2013-9-17
	 * @return 操作信息 */
	public String getMessage();

	/** 获取操作数据。
	 * <p>
	 * 如果操作结果是初始化，将抛出异常；如果是成功、失败或者异常，将返回对应的数据（非null），以便于后续处理。
	 * 
	 * @author 團長
	 * @since 2013-9-17
	 * @return */
	public T getData();

	/** 获取操作异常。当{@link #isException()}为false时，将返回一个NoException的特殊异常。
	 * 
	 * @author 團長
	 * @since 2013-9-17
	 * @return 
	 *         如果当前状态是INIT，则返回NoOperateYetException;如果是SUCCESS，将返回NoExceptionHappend异常
	 *         ；如果是FAIL，将返回一个BusinessFailException的实例 */
	@Deprecated
	public Exception getException();

	/** 判断操作结果是否为刚刚初始化
	 * 
	 * @author 團長
	 * @since 2013-9-17
	 * @return */
	@Deprecated
	public boolean isInit();

	/** 判断操作结果是否为成功
	 * 
	 * @author 團長
	 * @since 2013-9-17
	 * @return */
	public boolean isSuccess();

	/** 设定该操作结果的状态为操作成功，且返回数据为data
	 * 
	 * @author 團長
	 * @since 2013-9-18
	 * @param data
	 *            操作成功时的返回数据
	 * @throws NullPointerException
	 *             当data为null时，将抛出此异常。以此保证返回结果没有null */
	public void success(final T data) throws NullPointerException;

	/** 判断操作结果是否为失败
	 * 
	 * @author 團長
	 * @since 2013-9-17
	 * @return */
	public boolean isFail();

	/** 设定该操作结果的状态为操作失败，且返回数据为data，返回信息为message
	 * 
	 * @author 團長
	 * @since 2013-9-18
	 * @param data
	 *            操作失败时的返回数据。通常是一个初始化时的数据
	 * @param message
	 *            操作失败时的失败提示信息；如果入参为null、空字符串等，将初始化为“FAIL”
	 * @throws NullPointerException
	 *             当data为null时，将抛出此异常。以此保证返回结果没有null */
	public void fail(final T data, final String message)
			throws NullPointerException;

	/** 判断操作结果是否为发生异常
	 * 
	 * @author 團長
	 * @since 2013-9-17
	 * @return */
	@Deprecated
	public boolean isException();

	/** 设定该操作结果的状态为操作异常，且返回数据为data，返回信息为message，操作异常为e
	 * <p>
	 * 当message是null或者空字符串时，将使用e.getMessage()
	 * 
	 * @author 團長
	 * @since 2013-9-18
	 * @param data
	 *            操作异常时的返回数据。通常是一个初始化时的数据
	 * @param message
	 * @param e
	 * @throws NullPointerException */
	@Deprecated
	public void exception(final T data, final String message, final Exception e)
			throws NullPointerException;

	/** 设定该操作结果的状态为操作失败，返回信息为message
	 * 
	 * @author 團長
	 * @since 2014-3-12
	 * @param message
	 * @throws NullPointerException */
	public void fail(final String message) throws NullPointerException;

	/** 设定该操作结果的状态为操作异常，且返回信息为message，操作异常为e。
	 * <p>
	 * 当message是null或者空字符串时，将使用e.getMessage()作为默认信息
	 * 
	 * @author 團長
	 * @since 2013-9-18
	 * @param message
	 * @param e
	 * @throws NullPointerException */
	@Deprecated
	public void exception(final String message, final Exception e)
			throws NullPointerException;
}
